PsL Monthly 1993 December/PSL Monthly Shareware CD-ROM (December 1993).iso/prgmming/dos/c/xmsif.exe/XMSIF.DOC

Text File | 1992-11-14 | 44KB | 971 lines

                                 XMSIF
                      C Interface to XMS Functions
                           XMSIF version 1.42
                          by James W. Birdsall
                                11/14/92


0. CONTENTS
-----------

   0.     CONTENTS
   I.     INTRODUCTION
    I.1    WHAT IS SUPPORTED
    I.2    COPYRIGHT, LICENSE, AND WARRANTY DISCLAIMER
   II.    COMPILING AND LINKING WITH THE LIBRARIES
    II.1   WITH C
    II.2   WITH C++
    II.3   XMSTEST, THE EXAMPLE PROGRAM
   III.   PROGRAMMING WITH XMSIF
    III.1  INITIALIZING THE LIBRARY
    III.2  ORDINARY USE
    III.3  TIPS ON USING EMBS
    III.4  TIPS ON USING UMBS
    III.5  OTHER TIPS
    III.6  FUNCTION GROUPINGS
   IV.    LIBRARY REFERENCE
    IV.1   GLOBAL VARIABLES
    IV.2   EMB FUNCTIONS
    IV.3   UMB FUNCTIONS
   V.     ERROR CODES
    V.1    INTERNAL ERRORS
    V.2    XMS DRIVER ERRORS
   VI.    THE END
    VI.1   ACKNOWLEDGEMENTS


I. INTRODUCTION
---------------

   XMSIF provides a high-level interface to XMS control functions for
common operations such as allocating and freeing XMS extended memory
blocks (EMBs) and upper memory blocks (UMBs), and copying data to and
from EMBs. A raw interface to the driver has been included to allow more
convenient access to driver functions not otherwise supported.

   XMSIF is written in assembly language for speed and assembled with
Borland's Turbo Assembler (TASM) 2.5. The source code is not compatible
with the Microsoft Assembler (MASM).

 I.1 WHAT IS SUPPORTED
 ---------------------

   XMSIF expressly supports the Microsoft eXtended Memory Specification
(XMS) version 2.0. Versions below 2.0 are not supported. Versions above
2.0 are supported as 2.0.

   XMSIF supports tiny, small, medium, compact, large, and huge memory
models. The small model library supports both tiny and small models, so
no library is provided specifically for tiny model.

   XMSIF supports any version of Turbo C, Turbo C++, or Borland C++, in
both C and C++ modes, and Microsoft C 6.00/A and C/C++ 7.0. XMSIF has
been tested with Borland C++ 2.0, Turbo C 2.0, Microsoft C 6.00A, and
Microsoft C/C++ 7.0 in all of the supported memory models. XMSIF should
work with earlier versions of Microsoft C and any other MS-DOS C
compiler that 1) uses compatible parameter passing and return methods
and 2) can use standard-format libraries.

 I.2 COPYRIGHT, LICENSE, AND WARRANTY DISCLAIMER
 -----------------------------------------------

   XMSIF is not in the public domain. All the files are copyright 1991,
1992 by James W. Birdsall, all rights reserved. Permission is granted to
do the following:

        You may freely redistribute this archive, so long as it contains
        all the files listed in the file MANIFEST, intact and
        unmodified.

        You may use the libraries in programs for your own use. You may
        not distribute programs linked with these libraries.

   Payment of the $5 shareware registration fee ($50 for commercial use)
grants the following license, in addition to the permissions listed
above:

        You may request the source to XMSIF. You may modify the source
        as necessary for use in your programs. However, you may not
        redistribute either the original or modified source. There is no
        additional charge for source.

        You may distribute programs linked with either the original
        libraries or libraries generated from source you have modified,
        without royalty, provided you (a) do not alter or remove
        copyright notices contained therein and (b) you indemnify, hold
        harmless, and defend the author from and against any claims or
        lawsuits, including attorney's fees, that arise or result from
        the use or distribution of your software product.

For the purposes of this license, commercial use is defined as use by an
incorporated entity in a software product that is regarded as the
product of the corporation, no matter how the software product is
distributed, but only if 100 or more copies of the product are expected
to be made.

   Registered users will also receive update notices and bug reports,
and are entitled to use future versions without further payment.

   The contents of the distribution archive, and all other related
files, information, and services are provided "as is" and without
warranty. To the extent permitted by applicable law, the author
disclaims all warranties, express or implied, including but not limited
to, any implied warranty of merchantability or fitness for a particular
purpose. While effort has been made to ensure that the files, information,
and services are accurate and correct, the author shall not be liable
for damages arising out of the use of or inability to use this product,
including but not limited to, loss of profit, data, or use of this
software, or special, incidental, or consequential damages or other
similar claims, even if the author has been specifically advised of the
possibility of such damages. Some states do not allow the exclusion of
incidental or consequential damages, so the foregoing limitation may not
apply to you.

   Information on contacting the author is provided at the end of this
file.


II. COMPILING AND LINKING WITH THE LIBRARIES
--------------------------------------------

   This section describes how to use the XMSIF libraries with your
programs.

   XMSIF is provided as Borland/Microsoft standard library files.
Libraries are provided for small, medium, compact, large, and huge
memory models (tiny model uses the small model library). The model for
which a library is intended is indicated by the last letter of the
filename proper, which is the same as the first letter for the model.
For example, XMSIFL.LIB is the large model library.

 II.1 WITH C
 -----------

   To use XMSIF in C programs, you must #include the file XMSIF.H in
every source file that calls XMSIF functions, accesses XMSIF global
variables, or uses #defined constants provided by XMSIF.

   The procedures for linking XMSIF with the rest of your program vary
according to the compiler and method you are using. In general, you must
include the appropriate library (the library corresponding to the memory
model in which you have compiled the rest of your program) in the link.

   If you are compiling in the Integrated Development Environment of
Turbo/Borland C[++], you should include the name of the appropriate
library in the project file for your program. For example, if you are
working in the compact memory model, you should include XMSIFC.LIB in
your project file.

   If you are using a command-line compiler (bcc, tcc, or cl) to compile
and link, simply place the full name of the appropriate XMSIF library on
the command line. For example, "bcc -mc foo.c xmsifc.lib" will compile
the file "foo.c" in the compact model and link it with xmsifc.lib.

   If you are linking manually (using TLINK or LINK), place the name of
the appropriate library in with the other libraries. For example,
        tlink c0c.obj foo.obj, foo.exe, foo.map, cc.lib xmsifc.lib
or
        link foo.obj, foo.exe, foo.map, xmsifc.lib ;
will link the object "foo.obj" with the appropriate startup object and
standard library (LINK automatically includes the startup object and
standard library, so it is not necessary to explicitly include them) and
the compact model XMSIF library.

 II.2 C++
 --------

   To use XMSIF in C++ programs, you must #include the file XMSIF.HPP in
every file that calls XMSIF functions, accesses XMSIF global variables,
or uses #defined constants provided by XMSIF. Be careful to include
XMSIF.HPP instead of XMSIF.H. If you include the wrong one, you will
probably see "undefined symbol" errors when linking.

   Otherwise, the procedures for using XMSIF with C++ programs are the
same as for using it with C programs.

 II.3 XMSTEST, THE EXAMPLE PROGRAM
 ---------------------------------

   A large and complete example program and tester, XMSTEST, h